package com.tbynet.jwp.service.spi;

import com.jfinal.kit.Ret;
import com.jfinal.plugin.activerecord.Page;
import com.tbynet.jwp.model.Postmeta;
import com.tbynet.jwp.model.Posts;

import java.util.*;

/**
 * 文章管理编排层 - 优化重构版
 *
 * 核心职责：
 * 1. 文章生命周期管理（创建、更新、删除、发布）
 * 2. 分类标签关系管理
 * 3. 文章搜索和查询优化
 * 4. 缓存管理和性能优化
 *
 * 设计原则：
 * - 不包含任何SQL代码，只编排Service层方法
 * - 一个方法完成一个完整的业务用例
 * - 统一的事务管理和错误处理
 * - 支持性能监控和统计
 *
 * @author 佰亿互联
 * @version 3.1
 * @since 2025-11-04
 */
public interface PostManager {

    // ============ 文章生命周期管理 ============

    /**
     * 创建文章完整业务流程
     *
     * @param post 文章基本信息（必需）
     * @param postmetas 文章元数据列表（可选）
     * @param format 文章格式（可选）
     * @param categories 分类ID数组（可选）
     * @param tags 标签名称数组（可选）
     * @param sticky 是否置顶（可选）
     * @return Ret 创建结果，包含文章ID和操作状态
     *
     * @example
     * <pre>{@code
     * Posts post = new Posts();
     * post.setPostTitle("文章标题");
     * post.setPostContent("文章内容");
     *
     * List<Postmeta> metas = new ArrayList<>();
     * metas.add(new Postmeta().setMetaKey("key").setMetaValue("value"));
     *
     * Ret result = postManager.createPost(post, metas, "standard",
     *     new String[]{"1", "2"}, new String[]{"标签1", "标签2"}, true);
     * }</pre>
     */
    Ret createPost(final Posts post, final List<Postmeta> postmetas, final String format,
                          final String[] categories, final String[] tags, final Boolean sticky);

    /**
     * 更新文章完整业务流程
     *
     * @param post 更新后的文章信息（必需）
     * @param postmetas 更新后的元数据列表（可选）
     * @param format 文章格式（可选）
     * @param categories 分类ID数组（可选）
     * @param tags 标签名称数组（可选）
     * @param sticky 是否置顶（可选）
     * @return Ret 更新结果，包含操作状态和文章ID
     *
     * @example
     * <pre>{@code
     * Posts post = postManager.getPostDetail(1L);
     * post.setPostTitle("更新后的标题");
     *
     * Ret result = postManager.updatePost(post, null, "standard",
     *     new String[]{"3"}, new String[]{"新标签"}, false);
     * }</pre>
     */
    Ret updatePost(final Posts post, final List<Postmeta> postmetas, final String format,
                          final String[] categories, final String[] tags, final Boolean sticky);

    /**
     * 删除文章业务编排
     *
     * @param postId 文章ID（必需）
     * @return Ret 删除结果，包含操作状态
     *
     * @example
     * <pre>{@code
     * Ret result = postManager.deletePost(1L);
     * if (result.isOk()) {
     *     System.out.println("删除成功");
     * }
     * }</pre>
     */
    Ret deletePost(final Object postId);

    // ============ 文章查询和搜索 ============

    /**
     * 搜索文章业务编排（带缓存）
     *
     * @param pageNumber 页码（必需）
     * @param pageSize 每页大小（必需）
     * @param type 文章类型（可选，默认：post）
     * @param status 文章状态（可选）
     * @param keyword 搜索关键词（可选）
     * @return Page<Posts> 搜索结果分页对象
     *
     * @example
     * <pre>{@code
     * Page<Posts> result = postManager.searchPosts(1, 20, "post", "publish", "Java");
     * List<Posts> posts = result.getList();
     * long total = result.getTotalRow();
     * }</pre>
     */
    Page<Posts> searchPosts(final int pageNumber, final int pageSize, final String type,
                                   final String status, final String keyword);

    /**
     * 高级搜索文章业务编排
     *
     * @param pageNumber 页码（必需）
     * @param pageSize 每页大小（必需）
     * @param type 文章类型（可选，默认：post）
     * @param status 文章状态（可选）
     * @param keyword 搜索关键词（可选）
     * @param category 分类（可选）
     * @param tag 标签（可选）
     * @param month 月份（格式：YYYYMM）（可选）
     * @param sticky 是否置顶（可选）
     * @return Page<Posts> 搜索结果分页对象
     *
     * @example
     * <pre>{@code
     * Page<Posts> result = postManager.advancedSearchPosts(1, 20, "post", "publish",
     *     "Java", "技术", "编程", "202501", true);
     * }</pre>
     */
    Page<Posts> advancedSearchPosts(final int pageNumber, final int pageSize, final String type, final String status,
                                           final String keyword, final String category, final String tag,
                                           final String month, final Boolean sticky);

    /**
     * 获取文章详情业务编排（带缓存）
     *
     * @param postId 文章ID（必需）
     * @return Posts 文章详情对象，如果不存在返回null
     *
     * @example
     * <pre>{@code
     * Posts post = postManager.getPostDetail(1L);
     * if (post != null) {
     *     String title = post.getPostTitle();
     *     String content = post.getPostContent();
     * }
     * }</pre>
     */
    Posts getPostDetail(final Object postId);

    // ============ 置顶文章管理 ============

    /**
     * 获取置顶文章列表业务编排
     *
     * @return List<Posts> 置顶文章列表，如果没有置顶文章返回空列表
     *
     * @example
     * <pre>{@code
     * List<Posts> stickyPosts = postManager.getStickyPosts();
     * for (Posts post : stickyPosts) {
     *     System.out.println(post.getPostTitle());
     * }
     * }</pre>
     */
    List<Posts> getStickyPosts();

    /**
     * 检查文章是否置顶
     *
     * @param postId 文章ID（必需）
     * @return boolean 如果文章置顶返回true，否则返回false
     *
     * @example
     * <pre>{@code
     * boolean isSticky = postManager.isStickyPost(1L);
     * if (isSticky) {
     *     System.out.println("文章已置顶");
     * }
     * }</pre>
     */
    boolean isStickyPost(final Object postId);

    /**
     * 设置文章置顶状态业务编排
     *
     * @param postId 文章ID（必需）
     * @param sticky 是否置顶（必需）
     * @return Ret 操作结果，包含操作状态
     *
     * @example
     * <pre>{@code
     * // 置顶文章
     * Ret result1 = postManager.setSticky(1L, true);
     *
     * // 取消置顶
     * Ret result2 = postManager.setSticky(1L, false);
     * }</pre>
     */
    Ret setSticky(final Object postId, final boolean sticky);

    /**
     * 批量设置置顶状态业务编排
     *
     * @param postIds 文章ID列表（必需）
     * @param sticky 是否置顶（必需）
     * @return Ret 操作结果，包含操作状态
     *
     * @example
     * <pre>{@code
     * List<Object> postIds = Arrays.asList(1L, 2L, 3L);
     * Ret result = postManager.batchSetSticky(postIds, true);
     * }</pre>
     */
    Ret batchSetSticky(final List<Object> postIds, final boolean sticky);

    // ============ 批量操作管理 ============

    /**
     * 批量操作文章业务编排
     *
     * @param postIds 文章ID数组（必需）
     * @param action 操作类型（必需，可选值：trash|delete|restore）
     * @return Ret 操作结果，包含操作状态
     *
     * @example
     * <pre>{@code
     * // 移至回收站
     * Ret result1 = postManager.batchOperatePosts(new String[]{"1", "2"}, "trash");
     *
     * // 永久删除
     * Ret result2 = postManager.batchOperatePosts(new String[]{"1", "2"}, "delete");
     *
     * // 从回收站恢复
     * Ret result3 = postManager.batchOperatePosts(new String[]{"1", "2"}, "restore");
     * }</pre>
     */
    Ret batchOperatePosts(final String[] postIds, final String action);
}